/*
 * Copyright (c) 2009, 2013, Oracle and/or its affiliates. All rights reserved.
 * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 */

package java.lang;

/**
 * 可能持有资源（如文件或套接字句柄）直到关闭的对象。
 * 当退出在资源规范头中声明了该对象的 {@code try}-with-resources 块时，
 * {@code AutoCloseable} 对象的 {@link #close()} 方法会被自动调用。
 * 这种构造确保及时释放，避免可能发生的资源耗尽异常和错误。
 *
 * @apiNote
 * <p>基类实现 AutoCloseable 是可能的，实际上也很常见，
 * 即使并非其所有子类或实例都持有可释放的资源。
 * 对于必须在完全通用性下操作的代码，或者当已知 {@code AutoCloseable}
 * 实例需要资源释放时，建议使用 {@code try}-with-resources 构造。
 * 但是，当使用诸如 {@link java.util.stream.Stream} 这样既支持基于 I/O
 * 又支持非基于 I/O 形式的工具时，在使用非基于 I/O 的形式时，
 * {@code try}-with-resources 块通常是不必要的。
 *
 * @author Josh Bloch
 * @since 1.7
 */
public interface AutoCloseable {
    /**
     * 关闭此资源，放弃任何底层资源。
     * 此方法在由 {@code try}-with-resources 语句管理的对象上自动调用。
     *
     * <p>虽然此接口方法声明为抛出 {@code Exception}，但<em>强烈</em>鼓励实现者
     * 将 {@code close} 方法的具体实现声明为抛出更具体的异常，
     * 或者如果关闭操作不会失败则完全不抛出异常。
     *
     * <p>关闭操作可能失败的情况需要实现者仔细注意。
     * 强烈建议在抛出异常之前放弃底层资源并在内部<em>标记</em>资源为已关闭。
     * {@code close} 方法不太可能被调用超过一次，
     * 因此这确保了资源以及时的方式释放。
     * 此外，它减少了当资源包装或被另一个资源包装时可能出现的问题。
     *
     * <p><em>还强烈建议此接口的实现者不要让 {@code close} 方法抛出
     * {@link InterruptedException}。</em>
     *
     * 此异常与线程的中断状态交互，如果 {@code InterruptedException}
     * 被{@linkplain Throwable#addSuppressed 抑制}，则可能发生运行时错误行为。
     *
     * 更一般地说，如果异常被抑制会导致问题，
     * 则 {@code AutoCloseable.close} 方法不应该抛出它。
     *
     * <p>请注意，与 {@link java.io.Closeable} 的 {@link java.io.Closeable#close close}
     * 方法不同，此 {@code close} 方法<em>不</em>要求是幂等的。
     * 换句话说，多次调用此 {@code close} 方法可能会有一些可见的副作用，
     * 这与 {@code Closeable.close} 不同，后者要求如果被多次调用则没有效果。
     *
     * 但是，强烈鼓励此接口的实现者使其 {@code close} 方法幂等。
     *
     * @throws Exception 如果此资源无法关闭
     */
    void close() throws Exception;
}
